Documentation Guide#

Note

In file paths in this document, a leading / denotes the Sphinx source root.

Structure#

The documentation for the Oklahoma NG911 GIS Toolkit for ArcGIS Pro is comprised of a few main sections (source files/directories in parentheses):

  • User Manual (/user-manual)

  • ng911ok API Documentation (/apidoc)

  • Developer Guide (/developers)

  • Toolkit Glossary (/glossary.rst)

  • Validation Issue Glossary (validation-issues.rst)

The documentation is written in reStructuredText and built with Sphinx. It uses the PyData Sphinx Theme and that theme’s corresponding version of Sphinx Design. It uses a number of Sphinx extensions, including built-in extensions, custom extensions, and sphinxcontrib.programoutput.

Automatically-Generated Documentation#

The ng911ok API Documentation is generated from docstrings using the apidoc Sphinx extension (sphinx.ext.apidoc). The resulting output is written to /apidoc.

Supporting Files#

Images used in the documentation are stored in /images. Screenshots used in the User Manual section are stored in /images/UserManual.

Custom Sphinx Functionality#

Custom Extensions#

A number of custom Sphinx extensions have been written for this documentation. The added functionality is discussed below. The Python source files are stored in /_ext, and other supporting files, such as stylesheets, are stored in /_static.

Custom Sphinx Roles#

Note

As used by Sphinx, the term “role” denotes specially-interpreted text that may be rendered differently than the text around it. This is unrelated to the role attribute of the NG911Field and NG911FeatureClass classes.

In this section, the terms “Sphinx role” and “role attribute” will be used to distinguish between the two.

The following custom Sphinx roles are defined:

Sphinx Role

Rendered

Corresponds To

Example

ng911field

Field

NG911Field.role

:ng911field:`field_role_attribute`

ng911fc

Feature Class

NG911FeatureClass.role

:ng911fc:`feature_class_role_attribute`

ng911domain

Domain

NG911Domain.name

:ng911domain:`domain_name`

ng911ds

Feature Dataset

required or optional

:ng911ds:`required`

ng911tool

Validate Geodatabase

label attribute of tool classes in ng911ok.tools

:ng911tool:`Tool Name`

bdg-contrast, bdg-link-contrast, bdg-ref-contrast

Text

The provided interpreted text

:bdg-contrast:`Text`

bdg-contrast-line, bdg-link-contrast-line, bdg-ref-contrast-line

Text

The provided interpreted text

:bdg-contrast-line:`Text`

The :bdg-contrast:, :bdg-contrast-line, and similar Sphinx roles are derived from Sphinx Design’s bdg- Sphinx roles. Specifically, they are similar to :bdg-light:, :bdg-light-line (and similar) when the dark theme is active, and they are similar to :bdg-dark: and :bdg-dark-line: (and similar) when the light theme is active.

For :ng911field:, :ng911fc:, :ng911domain:, and :ng911ds:, if the text starts with a percent sign (%), that character itself will be removed, but whatever text that follows it will be preserved; this functionality is intended to be used only for demonstration purposes (e.g., to produce the contents of the “Rendered” column in the table above).

In the case of fields and feature classes, the provided role attribute will be replaced with the name attribute. This ensures that the correct field or feature class name will always be reflected when using these custom Sphinx roles, even if the name attributes change in a future version of the Standards.

For fields, the interpreted text can include, after the role, a comparison operator (=, <, >, <=, >=, !=) followed by arbitrary text. If the arbitary text starts with $ and is followed by an attribute of NG911Field, the value of that attribute will be inserted. For example, :ng911field:`addnumber>=0` will produce AddNumber ≥ 0, and :ng911field:`city=$fill_value` will produce City = UNINCORPORATED.

In the case of tools, the rendered output will link to the corresponding tool class in ng911ok.tools, but the text itself will not be changed.

These custom Sphinx roles are implemented in the modules in /_ext and the stylesheets are located in /_static (where / denotes the Sphinx source root).

Toolkit Documentation#

The Toolkit documentation is written in Markdown.

Using Visual Studio Code with the Markdown All in One extension, the documentation can be exported as HTML every time the Markdown files are saved.